JavaScript Module System

**Referenced Files in This Document** - [main.js](file://src/assets/js/main.js) - [navigation.js](file://src/assets/js/modules/navigation.js) - [carousel-system.js](file://src/assets/js/modules/carousel-system.js) - [theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [search-functionality.js](file://src/assets/js/modules/search-functionality.js) - [hero-animations.js](file://src/assets/js/modules/hero-animations.js) - [custom-cursor.js](file://src/assets/js/modules/custom-cursor.js) - [material-design-3-main-theme-toggle.js](file://src/assets/js/modules/material-design-3-main-theme-toggle.js) - [iaa-alliance-theme-toggle.js](file://src/assets/js/modules/iaa-alliance-theme-toggle.js) - [scroll-nav-polish.js](file://src/assets/js/modules/scroll-nav-polish.js) - [team-card-flip.js](file://src/assets/js/modules/team-card-flip.js) - [accordion.js](file://src/assets/js/modules/accordion.js) - [poll-bar-animation.js](file://src/assets/js/modules/poll-bar-animation.js) - [newsletter-spam-protection.js](file://src/assets/js/modules/newsletter-spam-protection.js) - [package.json](file://package.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains the JavaScript module system architecture used in the project’s frontend. It focuses on the ES6 modular design, the main orchestrator that bootstraps all features, and the responsibilities of each module. It also covers progressive enhancement, where animations are conditionally enabled when GSAP and ScrollTrigger are available, and how modules initialize, handle events, manipulate the DOM, and manage errors. The documented modules include navigation, carousels, theme toggling, search functionality, interactive elements, and animations.

Project Structure

The JavaScript runtime is organized around a single entry point that imports and initializes feature modules. Modules are grouped under a dedicated folder and exported as named functions designed to be invoked during DOMContentLoaded.

graph TB
M["main.js<br/>Entry Point"] --> N["navigation.js"]
M --> TT["theme-toggling.js"]
M --> CT["custom-cursor.js"]
M --> HA["hero-animations.js"]
M --> SP["scroll-nav-polish.js"]
M --> CS["carousel-system.js"]
M --> TCF["team-card-flip.js"]
M --> ACC["accordion.js"]
M --> PBA["poll-bar-animation.js"]
M --> MT["material-design-3-main-theme-toggle.js"]
M --> IAT["iaa-alliance-theme-toggle.js"]
M --> SF["search-functionality.js"]
M --> NSP["newsletter-spam-protection.js"]

Diagram sources

  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Section sources

  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Core Components

  • Orchestrator: The main entry point imports and invokes initialization functions for all modules. It guards animation features behind a runtime check for GSAP availability and registers ScrollTrigger if present.
  • Feature Modules: Each module exports a single initialization function responsible for binding DOM events, manipulating the DOM, and managing state for its feature area.
  • Progressive Enhancement: Animations and advanced interactions are enabled only when required libraries are loaded, ensuring core functionality remains intact without them.

Practical examples of module initialization and usage:

  • Navigation initialization is called on DOMContentLoaded and binds click, keyboard, and focus trap logic.
  • Carousels initialize per configuration, compute snap points, and wire buttons and keyboard navigation.
  • Theme toggles persist preferences to localStorage and apply appropriate body classes.
  • Search integrates PageFind dynamically and renders results with debounced input handling.
  • Animations are gated by GSAP presence and register ScrollTrigger only when available.

Section sources

  • [main.js:15-36](file://src/assets/js/main.js#L15-L36)
  • [navigation.js:3-75](file://src/assets/js/modules/navigation.js#L3-L75)
  • [carousel-system.js:3-166](file://src/assets/js/modules/carousel-system.js#L3-L166)
  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [search-functionality.js:3-176](file://src/assets/js/modules/search-functionality.js#L3-L176)
  • [hero-animations.js:3-307](file://src/assets/js/modules/hero-animations.js#L3-L307)

Architecture Overview

The system follows a modular, declarative bootstrap pattern:

  • The main orchestrator runs after DOMContentLoaded.
  • It initializes non-conditional features immediately.
  • It conditionally enables animations and advanced interactions only when external libraries are present.
sequenceDiagram
participant D as "DOM"
participant M as "main.js"
participant N as "navigation.js"
participant TT as "theme-toggling.js"
participant CS as "carousel-system.js"
participant MT as "material-design-3-main-theme-toggle.js"
participant IAT as "iaa-alliance-theme-toggle.js"
participant SF as "search-functionality.js"
participant CT as "custom-cursor.js"
participant HA as "hero-animations.js"
D->>M : "DOMContentLoaded"
M->>N : "initNavigation()"
M->>TT : "initThemeToggling()"
M->>CS : "initCarousels()"
M->>MT : "initThemeToggle()"
M->>SF : "initSearch()"
M->>IAT : "initIAAThemeToggle()"
M->>CT : "initCustomCursor()"
M->>HA : "initHeroAnimations()"
M->>CT : "initCustomCursor()"
M->>HA : "initScrollReveals()"

Diagram sources

  • [main.js:15-36](file://src/assets/js/main.js#L15-L36)
  • [navigation.js:3](file://src/assets/js/modules/navigation.js#L3)
  • [theme-toggling.js:3](file://src/assets/js/modules/theme-toggling.js#L3)
  • [carousel-system.js:3](file://src/assets/js/modules/carousel-system.js#L3)
  • [material-design-3-main-theme-toggle.js:3](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3)
  • [iaa-alliance-theme-toggle.js:3](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L3)
  • [search-functionality.js:3](file://src/assets/js/modules/search-functionality.js#L3)
  • [custom-cursor.js:3](file://src/assets/js/modules/custom-cursor.js#L3)
  • [hero-animations.js:3](file://src/assets/js/modules/hero-animations.js#L3)

Detailed Component Analysis

Navigation Module

Responsibilities:

  • Toggle mobile menu visibility and manage ARIA attributes.
  • Close on escape, outside clicks, and link selection.
  • Trap focus within the menu and support Tab/Shift+Tab navigation.
  • Manage body classes and accessibility attributes for screen readers.

Implementation highlights:

  • Event delegation and selective DOM queries.
  • Accessibility-first patterns: aria-expanded, aria-label updates, focus management.
  • Graceful degradation when required elements are missing.
flowchart TD
Start(["initNavigation"]) --> Query["Query toggle and menu"]
Query --> Exists{"Elements found?"}
Exists --> |No| Exit["Return early"]
Exists --> |Yes| BindClick["Bind click to toggle menu"]
BindClick --> CloseOnLink["Close on link click"]
CloseOnLink --> CloseOnEsc["Close on Escape key"]
CloseOnEsc --> FocusTrap["Focus trap with Tab/Shift+Tab"]
FocusTrap --> CloseOutside["Close on outside click"]
CloseOutside --> Exit

Diagram sources

  • [navigation.js:3-75](file://src/assets/js/modules/navigation.js#L3-L75)

Section sources

  • [navigation.js:3-75](file://src/assets/js/modules/navigation.js#L3-L75)

Carousel System Module

Responsibilities:

  • Initialize multiple carousels with shared logic.
  • Compute snap points based on viewport width and item sizing.
  • Render pagination dots and update active state.
  • Provide keyboard navigation and smooth scrolling.
  • Support drag-to-scroll gestures with mouse events.
  • Update state on scroll and window resize.

Implementation highlights:

  • Dynamic item counting and gap-aware layout calculations.
  • Debounced UI updates via passive listeners.
  • Accessibility attributes for ARIA compliance.
flowchart TD
Init(["initCarousels"]) --> Configs["Define carousel configs"]
Configs --> Setup["setupCarousel(cfg)"]
Setup --> Query["Query viewport and buttons"]
Query --> Items["Resolve track and items"]
Items --> Dots["Render pagination dots"]
Dots --> Scroll["Bind scroll and resize handlers"]
Scroll --> Keyboard["Bind arrow keys"]
Keyboard --> Drag["Bind mousedown/mousemove/mouseup"]
Drag --> Exit["Ready"]

Diagram sources

  • [carousel-system.js:3-166](file://src/assets/js/modules/carousel-system.js#L3-L166)

Section sources

  • [carousel-system.js:3-166](file://src/assets/js/modules/carousel-system.js#L3-L166)

Theme Toggling Module

Responsibilities:

  • Switch body classes based on intersecting themed sections.
  • Use an intersection observer with centered viewport thresholds.
  • Toggle light/dark indicators for background-aware content.

Implementation highlights:

  • IntersectionObserver with rootMargin tuned for mid-screen detection.
  • Minimal DOM writes by toggling a single element class.
flowchart TD
Start(["initThemeToggling"]) --> Sections["Query [data-theme] sections"]
Sections --> Observe["Create IntersectionObserver"]
Observe --> OnEntry["On entry: set body classes"]
OnEntry --> Exit["Observe until unneeded"]

Diagram sources

  • [theme-toggling.js:3-21](file://src/assets/js/modules/theme-toggling.js#L3-L21)

Section sources

  • [theme-toggling.js:3-21](file://src/assets/js/modules/theme-toggling.js#L3-L21)

Search Functionality Module

Responsibilities:

  • Open/close search modal and manage focus.
  • Dynamically import PageFind and configure options.
  • Debounce input to limit search requests.
  • Render categorized results with icons and excerpts.
  • Support keyboard navigation (arrow keys, Enter, Escape).
  • Provide a global shortcut to open the modal.

Implementation highlights:

  • Async import for lazy loading PageFind.
  • Debounced search with a short timer.
  • Result rendering with category detection from URLs.
  • Global keyboard shortcut handling.
sequenceDiagram
participant U as "User"
participant SF as "search-functionality.js"
participant PF as "PageFind"
U->>SF : "Click search toggle"
SF->>SF : "openModal()"
SF->>PF : "import('/pagefind/pagefind.js')"
U->>SF : "Type in input"
SF->>SF : "Debounce 200ms"
SF->>PF : "performSearch(query)"
PF-->>SF : "results"
SF->>SF : "Render results"
U->>SF : "ArrowDown/Up/Enter"
SF->>SF : "Update selection and navigate"

Diagram sources

  • [search-functionality.js:3-176](file://src/assets/js/modules/search-functionality.js#L3-L176)

Section sources

  • [search-functionality.js:3-176](file://src/assets/js/modules/search-functionality.js#L3-L176)

Hero Animations Module

Responsibilities:

  • Initialize homepage hero animations or fallback reveals for other pages.
  • Manage particle canvas background and Three.js-driven hero scenes.
  • Animate SVG elements (topographic lines, Southern Cross).
  • Coordinate ScrollTrigger-driven parallax effects.
  • Provide reduced-motion friendly sequences.
  • Expose helpers for scroll-triggered reveals elsewhere.

Implementation highlights:

  • Conditional logic to avoid double-initialization when Three.js is active.
  • Timeline-based sequencing with staggered delays.
  • Scroll-driven parallax controlled via ScrollTrigger.
flowchart TD
Start(["initHeroAnimations"]) --> ParallaxCheck{"Parallax hero present?"}
ParallaxCheck --> |Yes| Exit["Return (handled elsewhere)"]
ParallaxCheck --> |No| HomeCheck{"Homepage hero?"}
HomeCheck --> |Yes| ReducedCheck{"prefers-reduced-motion?"}
ReducedCheck --> |Yes| ReducedTL["Build reduced-motion timeline"]
ReducedCheck --> |No| FullTL["Initialize cross, topo, nav-path"]
HomeCheck --> |No| OtherTL["Build generic hero timeline"]
FullTL --> Exit
ReducedTL --> Exit
OtherTL --> Exit

Diagram sources

  • [hero-animations.js:3-44](file://src/assets/js/modules/hero-animations.js#L3-L44)

Section sources

  • [hero-animations.js:3-307](file://src/assets/js/modules/hero-animations.js#L3-L307)

Additional Interactive Modules

  • Custom Cursor: Desktop-only hover-follow cursor with GSAP animations and hover state toggles.
  • Scroll Nav Polish: Adjust navbar padding/shadow on scroll.
  • Team Card Flip: Touch-friendly flip behavior for team cards.
  • Accordion: Single-open accordion with dynamic height calculation.
  • Poll Bar Animation: IntersectionObserver-driven width animation for poll segments.
  • Newsletter Spam Protection: ConvertKit form protection via honeypot and timing checks.

Section sources

  • [custom-cursor.js:3-25](file://src/assets/js/modules/custom-cursor.js#L3-L25)
  • [scroll-nav-polish.js:3-15](file://src/assets/js/modules/scroll-nav-polish.js#L3-L15)
  • [team-card-flip.js:3-10](file://src/assets/js/modules/team-card-flip.js#L3-L10)
  • [accordion.js:3-31](file://src/assets/js/modules/accordion.js#L3-L31)
  • [poll-bar-animation.js:3-16](file://src/assets/js/modules/poll-bar-animation.js#L3-L16)
  • [newsletter-spam-protection.js:3-23](file://src/assets/js/modules/newsletter-spam-protection.js#L3-L23)

Dependency Analysis

Runtime dependencies and gating:

  • GSAP and ScrollTrigger: Required for animations. The orchestrator checks for their presence and conditionally enables advanced features. ScrollTrigger is registered only when available.
  • PageFind: Dynamically imported for search functionality to avoid blocking initial load.
  • LocalStorage: Used by theme toggles to persist user preference.
  • IntersectionObserver: Used by theme toggling and scroll reveals.
  • Passive event listeners: Applied to scroll and resize handlers for performance.
graph LR
M["main.js"] --> G["GSAP"]
M --> ST["ScrollTrigger"]
SF["search-functionality.js"] --> PF["PageFind (/pagefind/pagefind.js)"]
MT["material-design-3-main-theme-toggle.js"] --> LS["localStorage"]
IAT["iaa-alliance-theme-toggle.js"] --> LS
TT["theme-toggling.js"] --> IO["IntersectionObserver"]
HA["hero-animations.js"] --> IO

Diagram sources

  • [main.js:28-35](file://src/assets/js/main.js#L28-L35)
  • [search-functionality.js:18-28](file://src/assets/js/modules/search-functionality.js#L18-L28)
  • [material-design-3-main-theme-toggle.js:8-26](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L8-L26)
  • [iaa-alliance-theme-toggle.js:8-26](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L8-L26)
  • [theme-toggling.js:9-20](file://src/assets/js/modules/theme-toggling.js#L9-L20)
  • [hero-animations.js:283-304](file://src/assets/js/modules/hero-animations.js#L283-L304)

Section sources

  • [main.js:28-35](file://src/assets/js/main.js#L28-L35)
  • [search-functionality.js:18-28](file://src/assets/js/modules/search-functionality.js#L18-L28)
  • [material-design-3-main-theme-toggle.js:8-26](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L8-L26)
  • [iaa-alliance-theme-toggle.js:8-26](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L8-L26)
  • [theme-toggling.js:9-20](file://src/assets/js/modules/theme-toggling.js#L9-L20)
  • [hero-animations.js:283-304](file://src/assets/js/modules/hero-animations.js#L283-L304)

Performance Considerations

  • Lazy loading:
    • PageFind is dynamically imported to avoid blocking initial load.
    • Animations are gated by library presence to prevent unnecessary work.
  • Event listener efficiency:
    • Scroll and resize listeners use passive options.
    • IntersectionObserver avoids continuous ticking for scroll-driven effects.
  • Memory and reflow minimization:
    • Batched DOM updates and minimal class toggles.
    • Avoid forced synchronous layouts by computing sizes once per update cycle.
  • Initialization order:
    • Non-conditional features run first, followed by conditional animations after DOMContentLoaded.
  • Plugin registration:
    • ScrollTrigger is registered only when available, preventing errors and extra overhead.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and strategies:

  • Missing DOM elements:
    • Many modules return early if required selectors are absent. Verify markup exists for toggles, modals, carousels, and theme sections.
  • Animation not playing:
    • Confirm GSAP and ScrollTrigger globals are available. The orchestrator logs a warning and skips animations when missing.
  • Search not working:
    • Ensure PageFind is built and served at the expected path. The module handles missing imports gracefully and logs a warning.
  • Theme toggle not persisting:
    • Check localStorage availability and permissions in the browser.
  • Carousel not updating dots:
    • Resize and scroll handlers rely on passive listeners; ensure viewport and item widths are measurable and gaps are defined.

Section sources

  • [main.js:33-35](file://src/assets/js/main.js#L33-L35)
  • [search-functionality.js:24-27](file://src/assets/js/modules/search-functionality.js#L24-L27)
  • [material-design-3-main-theme-toggle.js:10-11](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L10-L11)
  • [carousel-system.js:111-114](file://src/assets/js/modules/carousel-system.js#L111-L114)

Conclusion

The project employs a clean, modular ES6 architecture with a single orchestrator that coordinates feature initialization. Modules encapsulate responsibilities, leverage progressive enhancement for animations, and implement robust accessibility and performance practices. The design ensures graceful degradation when optional libraries are unavailable while delivering rich interactivity when supported.